Using the CALL Statement to Access User-Provided Functions
External routines linked in via call.c should be referenced by prefixing their names with a '.' in the CALL statement. For example, one might use
CALL .myfunc RESIDENT? Y END? N FAIL 3
to call a user-provided function named 'myfunc'.
The calling conventions used depend on the type of data passed to APPX, and whether or not you are passing the data as shared or not.
Alpha fields passed to a user-provided function, whether as shared or unshared data items, should be declared, and used, in the C function as 'char *'.
Binary fields are handled differently, based on a number of criteria. APPX will pass a BINARY field to a called C function as either a 1-byte, 2-byte or 4-byte integer, depending on how the field is defined. This is important to take into account, when declaring the parameters to your C function. If the parameter definitions don't match the sizes of fields sent to the function by APPX, you may notice that the values of your parameters are off by 256, 64 or some other multiple of 2, when your function runs. Guidelines used by APPX to determine how a binary field is passed to a called function include:
If the field, as defined in APPX, includes a range check to verify that it is within the size which can be stored in one byte, and the field includes 3 digits or less, then APPX will pass the field as a 1-byte integer. For signed APPX fields, the range check should be -127 <= x <= 127, and for unsigned APPX fields, the range check should be 0 <= x <= 256. The C declaration used to access this parameter would be 'char' (signed) or 'unsigned char' (unsigned), if it has been passed with SHARE?=N; 'char *' or 'unsigned char *' respectively, if passed with SHARE?=Y.
If the field, as defined in APPX, includes a range check to verify that it is within the size which can be stored in two bytes, and the field includes 5 digits or less, then APPX will pass the field as a 2-byte integer. For signed APPX fields, the range check should be -32767 <= x <= 32767, and for unsigned APPX fields, the range check should be 0 <= x <= 65535. The C declaration used to access this parameter would be 'short int' (signed) or 'unsigned short int' (unsigned), if it has been passed with SHARE?=N; 'short int *' or 'unsigned short int *' respectively, if passed with SHARE?=Y.
Otherwise, the field is passed as a 4-byte integer. The C declaration used to access this parameter would be 'int' (signed) or 'unsigned int' (unsigned), if it has been passed with SHARE?=N; 'int *' or 'unsigned int *' respectively, if passed with SHARE?=Y.
|